home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #5 / Amiga Plus CD - 2000 - No. 5.iso / Tools / Dev / GameboyDev / GBDK / doc / gbdk-doc.sgml < prev    next >
Encoding:
SGML Document  |  1999-03-29  |  56.2 KB  |  1,638 lines

  1. <!DOCTYPE Book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
  2. <book>
  3.     <title>GBDK libraries documentation</title>
  4.     <bookinfo>
  5.     <bookbiblio>
  6.         <authorgroup>
  7.             <author><firstname>Michael</firstname><surname>Hope</surname></author>
  8.             <author><firstname>Pascal</firstname><surname>Felber</surname></author>
  9.         </authorgroup>
  10.         <productname>
  11.             GBDK-2.0b13
  12.         </productname>
  13.         <pubdate>
  14.             August 31st 1998
  15.         </pubdate>
  16.         <copyright>
  17.             <year>1998</year>
  18.             <holder>Michael Hope, Pascal Felber</holder>
  19.         </copyright>
  20.         <abstract>
  21.             <para>
  22.                 This document is a first try at documenting the Gameboy Developers Kit (GBDK)
  23.                 by Pascal Felber which consists of a C compiler, assembler, linker and libraries.
  24.                 Included are methods of writing efficent eight bit code in C, ways of
  25.                 accessing the GBs hardware, interfacing assembler and C and a list of the
  26.                 functions provided by the libraries.
  27.             </para>
  28.         </abstract>
  29.     </bookbiblio>
  30.     </bookinfo>
  31.     <toc></toc>
  32.     <preface id="preface">
  33.         <title>Preface</title>
  34.         <para>
  35.             Why
  36.         </para>
  37.     </preface>
  38.     <chapter id="using-gbdk">
  39.         <title>Using GBDK and maccer</title>
  40.         <sect1>
  41.             <title>Compiling programs</title>
  42.             <para>
  43.                 This section assumes that you have installed GBDK properly and
  44.                 build the libraries as per the instructions on <ulink url="http://lsewww.epfl.ch/~felber/GBDK/">
  45.                 Pascal's homepage</ulink>.
  46.             </para>
  47.             <para>
  48.                 The program 'lcc' is a front end for the actual compiler, assembler
  49.                 and linker.  It works out what you want to do based on command line options
  50.                 and the extensions of the files you give it, computes the order in which
  51.                 the various programs must be called and then executes them in order.
  52.                 Some examples are:
  53.                 <itemizedlist>
  54.                     <listitem>
  55.                         <para>
  56.                             <literal>lcc -o image.gb source.c</literal> - compile the C source 'source.c',
  57.                             assemble and link it producing the Gameboy image 'image.gb'
  58.                         </para>
  59.                     </listitem>
  60.                     <listitem>
  61.                         <para>
  62.                             <literal>lcc -o image.gb source.s</literal> - assemble the file
  63.                             'source.s' and link it producing the Gameboy image 'image.gb'
  64.                         </para>
  65.                     </listitem>
  66.                     <listitem>
  67.                         <para>
  68.                             <literal>lcc -c -o object1.o source1.c</literal> - compile the
  69.                             C program 'source1.c' and assemble it producing the object
  70.                             file 'object1.o' for later linking.
  71.                         </para>
  72.                     </listitem>
  73.                     <listitem>
  74.                         <para>
  75.                             <literal>lcc -c -o object2.o source2.s</literal> - assemble the
  76.                             file 'source2.s' producing the object file 'object2.o'
  77.                             for later linking
  78.                         </para>
  79.                     </listitem>
  80.                     <listitem>
  81.                         <para>
  82.                             <literal>lcc -o image.gb object1.o object2.o</literal> - link
  83.                             the two object files 'object1.o' and 'object2.o' and
  84.                             produce the Gameboy image 'image.gb'
  85.                         </para>
  86.                     </listitem>
  87.                     <listitem>
  88.                         <para>
  89.                             <literal>lcc -o image.gb source1.c source2.s</literal> -
  90.                             do all sorts of clever stuff by compiling then assembling
  91.                             source1.c, assembling source2.s and then linking them
  92.                             together to produce image.gb.
  93.                         </para>
  94.                     </listitem>
  95.                 </itemizedlist>
  96.             </para>
  97.             <para id="link-arguments">
  98.                 Arguments to the assembler etc can be passed via lcc using
  99.                 <literal>-Wp..., -Wf..., -Wa...</literal> and <literal>-Wl...</literal>
  100.                 to pass options to the pre-processor, compiler, assembler and linker
  101.                 respectivly.  Some common options are:
  102.                 <itemizedlist>
  103.                     <listitem>
  104.                         <para>
  105.                             <literal>-Wa-l</literal> to generate an assembler listing file.
  106.                         </para>
  107.                     </listitem>
  108.                     <listitem>
  109.                         <para>
  110.                             <literal>-Wl-m</literal> to generate a linker map file which can
  111.                             then be turned into a
  112.                             <ulink url="http://www.work.de/nocash/gmb.htm">no$gmb</ulink>
  113.                             .sym file for debugging using
  114.                             <ulink url="http://www.pcmedia.co.nz/~michaelh/">maptosym</ulink>.
  115.                         </para>
  116.                     </listitem>
  117.                     <listitem>
  118.                         <para>
  119.                             <literal>-Wl-gvar=addr</literal> to bind var to address
  120.                             'addr' at link time.
  121.                         </para>
  122.                     </listitem>
  123.                 </itemizedlist>
  124.                 For example, to compile the example in the <link linkend="gb-hw-memory">memory</link>
  125.                 section and to generate a listing and map file you would use:
  126.                 <synopsis>
  127. lcc -Wa-l -Wl-m -Wl-g_snd_stat=0xff26 -o image.gb hardware.c
  128.                 </synopsis>
  129.                 Note the leading underscore that C adds to symbol names.
  130.             </para>
  131.             <para>
  132.                 Unfortunatly <ulink url="http://www.pcmedia.co.nz/~michaelh/">maccer</ulink>,
  133.                 Michael Hope's macro preprocessor for the assembler has to be run
  134.                 seperatly as lcc dosnt know about it.  To turn the assembler file
  135.                 with macros 'source.ms' into the assembler file 'source.s', use
  136.                 <synopsis>
  137. maccer -o source.s source.ms
  138.                 </synopsis>
  139.                 If the <literal>-o source.s</literal> option isnt specified then
  140.                 maccer writes to stdout.  If <literal>source.ms</literal> isnt
  141.                 specified then maccer reads from stdin.
  142.             </para>
  143.         </sect1>
  144.         <sect1 id="using-makefiles">
  145.             <title>Using Makefiles</title>
  146.             <para>
  147.                 One of the most useful development tools is 'make', a program that automatically
  148.                 keeps your object files and images up to date with your source code.
  149.                 It works by having a set of rules of how to get from one file
  150.                 type to another, which normally involves running a program.  For example
  151.                 by typing 'make image.gb' make will look for a C or assembler file
  152.                 called image.c or image.s, compile it and link it automatically creating
  153.                 the image image.gb.  It really comes into its own when you have
  154.                 a project made up of multiple files as it only recompiles those that
  155.                 have changed since the last make.
  156.             </para>
  157.             <para>
  158.                 A copy of GNU make for DOS is available as part of <ulink url="http://www.delorie.com/djgpp/">DJGPP</ulink>.
  159.                 Most Unix systems come with make installed.
  160.             </para>
  161.             <para>
  162.                 A general Makefile for Gameboy projects follows:
  163.                 <synopsis>
  164. AS = lcc -c
  165. CC = lcc -Wa-l -Wl-m
  166.  
  167. BIN = astro.gb
  168. OBJS =  render.o sin_table.o stars.o debug.o fp_long.o sqrt.o floor.o \
  169.         ftou.o sin_cos.o const.o inv_trig.o
  170.  
  171. all: $(BIN)
  172.  
  173. %.s: %.ms
  174.      maccer -o $@ $<
  175.  
  176. $(BIN): $(OBJS)
  177.      $(CC) -o $(BIN) $(OBJS)
  178.  
  179. clean:
  180.      rm -f $(BIN) $(OBJS) *~
  181.                 </synopsis>
  182.                 The first two lines convince make to use lcc as the assembler and
  183.                 linker instead of the default system ones.  The BIN line
  184.                 specifies the name of the image file you want at the end.  The OBJS
  185.                 line specifies what object files must be made for BIN to be built.
  186.                 The %.s: %.ms line tells make how to generate .s files for lcc
  187.                 from .ms (macro) files.
  188.             </para>
  189.             <para>
  190.                 For example, suppose that I change the assembler file 'render.ms'.
  191.                 When make is run, it will find that astro.gb depends on render.o
  192.                 which in turn depends on render.ms.  It will then use maccer
  193.                 to change the astro.ms file to astro.s, then it will use lcc
  194.                 to assemble astro.s to astro.o which is finally linked with all
  195.                 the other .o files to create astro.gb
  196.             </para>
  197.         </sect1>
  198.     </chapter>
  199.     <chapter id="gb-target">
  200.         <title>The Gameboy as a Target</title>
  201.         <sect1>
  202.             <title>8 bits + 6 registers + C = tricky</title>
  203.             <para>
  204.                 The Gameboy is not an ideal target for C code due to a combination
  205.                 of being eight bit, having a small register set (pity
  206.                 those who have the 6502 as a target...), no indexed addressing
  207.                 mode and no hardware multiplication or division.  The processor
  208.                 being eight bit is the biggest limitation as most modern C assumes
  209.                 that an int is at least 16 bits - see later.
  210.             </para>
  211.             <para>
  212.                 This section is on the methods used to get around or avoid
  213.                 the limitations    of the processor which boils down to ways
  214.                 of staying within eight bits.
  215.             </para>
  216.         </sect1>
  217.         <sect1>
  218.             <title>Size of variables</title>
  219.             <para>
  220.                 The size of the various types as at 2.0b13 are:
  221.                 <itemizedlist>
  222.                     <listitem>
  223.                         <para>
  224.                             <literal>char          </literal>eight bit signed
  225.                         </para>
  226.                     </listitem>
  227.                     <listitem>
  228.                         <para>
  229.                             <literal>unsigned char </literal>eight bit unsigned
  230.                         </para>
  231.                     </listitem>
  232.                     <listitem>
  233.                         <para>
  234.                             <literal>int           </literal>eight bit signed
  235.                         </para>
  236.                     </listitem>
  237.                     <listitem>
  238.                         <para>
  239.                             <literal>unsigned int  </literal>eight bit unsigned
  240.                         </para>
  241.                     </listitem>
  242.                     <listitem>
  243.                         <para>
  244.                             <literal>long          </literal>sixteen bit signed
  245.                         </para>
  246.                     </listitem>
  247.                     <listitem>
  248.                         <para>
  249.                             <literal>unsigned long </literal>sixteen bit unsigned
  250.                         </para>
  251.                     </listitem>
  252.                     <listitem>
  253.                         <para>
  254.                             <literal>long long      </literal>32 bit signed
  255.                         </para>
  256.                     </listitem>
  257.                     <listitem>
  258.                         <para>
  259.                             <literal>unsigned long long </literal>32 bit unsigned
  260.                         </para>
  261.                     </listitem>
  262.                     <listitem>
  263.                         <para>
  264.                             <literal>float       </literal> 8 bit exponent, 24 bit mantissa
  265.                         </para>
  266.                     </listitem>
  267.                     <listitem>
  268.                         <para>
  269.                             <literal>pointer       </literal>two byte
  270.                         </para>
  271.                     </listitem>
  272.                 </itemizedlist>
  273.                 Please see the section on the <link linkend="float-lib">float library</link>
  274.                 for more information on the format of floating point numbers.  As
  275.                 at 2.0b13 neither float or long long support is complete.
  276.             </para>
  277.             <para>
  278.                 lcc uses 'int' as the default type for most operations including
  279.                 array indexing and constants.  To make the code more efficient
  280.                 the ints were made eight bit which unfortunately limits local arrays to
  281.                 less than 128 elements.  Note that statically allocated arrays
  282.                 such as image or tile data dont have this limitation.
  283.             </para>
  284.             <para>
  285.                 To make it easier for porting and if/when the size of an int gets
  286.                 changed, it is recommended that the types <literal>BYTE, UBYTE,
  287.                 WORD</literal> and <literal>UWORD</literal> defined in <literal>type.h</literal>
  288.                 are used.
  289.             </para>
  290.         </sect1>
  291.         <sect1>
  292.             <title>Avoiding Promotion</title>
  293.             <para>
  294.                 lcc assumes that any parameters in an expression are signed by
  295.                 default which can cause unnecessary promotion.  Promotion is
  296.                 where the compiler believes that the result of an operation will
  297.                 overflow and so it promotes the variable up a size, performs the
  298.                 operation and then demotes it back to the proper size.  For example in:
  299.                 <synopsis>
  300.     UBYTE i, j = 0;
  301.     i = j+0x80;
  302.                 </synopsis>
  303.                 The compiler assumes that the argument is signed, and as 0x80
  304.                 is greater than the biggest eight bit signed number 0x7f it is
  305.                 promoted to sixteen bit.  The operation is performed then the
  306.                 result truncated.
  307.                 </para>
  308.                 <para>
  309.                 This can be solved by explicitly telling the compiler that the
  310.                 argument is unsigned by adding a trailing U.  A better version
  311.                 of the above code is:
  312.                 <synopsis>
  313.     UBYTE i, j = 0;
  314.     i = j+0x80U;
  315.                 </synopsis>
  316.             </para>
  317.             <para>
  318.                 Changing the order of operations in a function can also stop
  319.                 promotion.  ??why??
  320.             </para>
  321.         </sect1>
  322.         <sect1>
  323.             <title>Using global variables</title>
  324.             <para>
  325.                 The local variables of a function are stored on the stack,
  326.                 requiring the compiler to calculate a variables absolute address
  327.                 every time its used.  By declaring a variable as global it
  328.                 becomes statically allocated at an address in ram which in
  329.                 most cases makes the code more efficient.
  330.             </para>
  331.             <para>
  332.                 Don't forget that global variables are still bad - but in this
  333.                 case its more efficient to use them.
  334.             </para>
  335.             <para>
  336.                 Globals are especially good for large structures.  The easiest
  337.                 way to access data on the stack is with the <literal>lda hl,x(sp)</literal>
  338.                 where x is a signed byte.  If the size of the local variables is
  339.                 greater than 127 bytes (the upper limit of a signed byte) then
  340.                 significantly slower code is used.
  341.             </para>
  342.         </sect1>
  343.         <sect1>
  344.             <title>Other</title>
  345.             <para>
  346.                 Preferably use the equality operators <literal>==</literal> and
  347.                 <literal>!=</literal> over the inequality operators
  348.                 <literal>>, <, <=</literal> and <literal>=></literal>.  If the
  349.                 operands are signed or long then the code for inequality significantly
  350.                 more complex then for unsigned bytes which can be done in two
  351.                 operations.
  352.             </para>
  353.             <para>
  354.                 Global variables that are initialised when they declared (for example
  355.                 <literal>int i = 0;</literal>) are put into the _DATA segment
  356.                 by lcc.  This means that the variable cant be changed as for
  357.                 the GB the _DATA segment is in ROM.  To avoid this, 
  358.                 its best to initialise any global variables after declaring them i.e. use
  359.                 <synopsis>
  360. int i;
  361.  
  362. int main(void)
  363. {
  364.     i = 0;
  365. };
  366.                 </synopsis>
  367.                 instead of the above code.
  368.             </para>
  369.         </sect1>
  370.     </chapter>
  371.     <chapter id="gb-hardware">
  372.         <title>Accessing hardware</title>
  373.         <sect1 id="gb-hw-memory">
  374.             <title>Memory</title>
  375.             <para>
  376.                 There are two main ways of accessing the memory of the GB directly.
  377.                 The first which I recommend is using casting, where the second
  378.                 is by declaring an address as external and defining it at link time.
  379.                 Both are best illustrated by example.  Suppose that you want to
  380.                 turn on sound by writing 8fh to SND_STAT (FF26h).  The code using casts
  381.                 is <synopsis>
  382. #define SND_STAT    (UBYTE *)0xFF26U
  383.  
  384. void sound_on(void)
  385. {
  386.     *SND_STAT = 0x8FU;
  387. }
  388.                 </synopsis>
  389.                 while the code using late linking is
  390.                 <synopsis>
  391. extern UBYTE snd_stat;
  392.  
  393. void sound_on(void)
  394. {
  395.     snd_stat = 0x8FU;
  396. }
  397.                 </synopsis>
  398.                 where snd_stat is defined at link time by adding
  399.                 <literal>-gsnd_stat=0xff26</literal> to the <link linkend="link-arguments">linker arguments.</link>
  400.             </para>
  401.             <para>
  402.                 The most comonly used hardware registers are pre-defined in <link linkend="hardware-h">hardware.h</link> using the late
  403.                 linking method.  This code 
  404.                 <synopsis>
  405. #include <hardware.h>
  406.  
  407. void sound_on(void)
  408. {
  409.     NR52_REG = 0x8fU; /* 'NR52_REG' maps to '_reg_0x26' or SND_STAT */
  410. }
  411.                 </synopsis>
  412.                 achieves the same as the other two examples.
  413.             </para>
  414.         </sect1>
  415.         <sect1>
  416.             <title>Interrupts</title>
  417.             <para>
  418.                 Interrupts allow execution to jump to a different part of your
  419.                 code as soon as an external event occurs - for example the LCD
  420.                 entering the vertical blank period, serial data arriving or the
  421.                 timer reaching its end count.  For an example see <literal>irq.c</literal>
  422.             </para>
  423.             <para>
  424.                 Interrupts in GBDK are handled using the functions
  425.                 <literal>disable_interrupts(), enable_interrupts(), set_interrupts(UBYTE ier)</literal>
  426.                 and the interrupt service routine (ISR) linkers <literal>add_VBL,
  427.                 add_TIM, add_LCD, add_SIO</literal> and <literal>add_JOY</literal>
  428.                 which add interrupt handlers for the vertical blank, timer, LCD,
  429.                 serial and joypad interrupts respectively.  The system supports up to 
  430.                 eight ISRs per interrupt, executing the first one installed first.
  431.             </para>
  432.             <para>
  433.                 As an example, this code installs an interrupt handler that increases
  434.                 <literal>count</literal> every time the timer runs out.
  435.                 <synopsis>
  436. ...
  437. UWORD count;
  438.  
  439. void timer_isr(void)
  440. {
  441.     count++;
  442. }
  443.  
  444. int setup_isr(void)
  445. {
  446.     disable_interrupts();
  447.     add_TIM(timer_isr);
  448.     enable_interrupts();
  449.  
  450.     set_interrupts(TIM_IFLAG);
  451. }
  452. ...
  453.             </synopsis>
  454.                 Note that this assumes that the timer is setup elsewhere and the use
  455.                 of the global variable.  All registers are pushed before the
  456.                 ISR is called.
  457.             </para>
  458.             <para>
  459.                 As an interrupt can occur at any time, an ISR cannot take any
  460.                 arguments or return anything.  Its only way of communicating
  461.                 with the greater program is through the global variable above.
  462.                 Note how interrupts have to be disabled before adding the timer
  463.                 ISR and that the set_interrupts call will disable any other interrupts.
  464.                 To use multiple interrupts, or the relevant IFLAGs together.
  465.             </para>
  466.             <para>
  467.                 ISRs must be kept as small and short as possible and as at 2.0b13
  468.                 cannot use any <literal>long long</literal>s or floating point variables as the code
  469.                 for them is not re-entrant.  It is possible to write a ISR long
  470.                 enough so that the GB spends all of its time servicing interrupts
  471.                 and has no time spare for the main code.
  472.             </para>
  473.         </sect1>
  474.         <sect1>
  475.             <title>Multiple banks</title>
  476.             <para>
  477.                 The GB supports ROMS of up to 1.5MB and up to 32kB of RAM by
  478.                 using a bank switching method.  Bank 0 of the ROM is always located
  479.                 in the region 0000h - 3FFFh and cannot be swapped but any other
  480.                 bank can be swapped into the high ROM region between 4000h to 7FFFh.
  481.                 Unfortunately GBDK doesn't support programs bigger than 32kB at the
  482.                 moment which is partly due to lcc assuming a flat address space.  However
  483.                 you can manually access the other banks using the
  484.                 <literal>switch_rom_bank(UBYTE)</literal> and <literal>switch_ram_bank</literal>
  485.                 functions.  See <literal>banks.c</literal> for an example.
  486.             </para>
  487.             <para>
  488.                 The ROM and RAM bank that the code should exist in is specified
  489.                 at compile time using the <literal>-Wf-box</literal> and
  490.                 <literal>-Wf-bax</literal> compiler options where x is the bank number
  491.                 between 1 and 31.  Note that this
  492.                 means that you cant switch banks within one code file but multiple
  493.                 files can exist in the same bank.  If neither the -bo or -ba options
  494.                 are given then the default _CODE and _BSS segments are used.  Dont
  495.                 forget that local variables are allocated on the stack inside _BSS.
  496.             </para>
  497.             <para>
  498.                 For example, suppose the code:
  499.                 <synopsis>
  500. int silly_fun( int a )
  501. {
  502.     printf("%i times %i is ", a, a, a*a+1 );
  503.     return 0;
  504. }
  505.                 </synopsis>
  506.                 was compiled with the <literal>-Wf-bo1</literal> compiler option
  507.                 then the code would be stored in segment <literal>_CODE_1</literal>.
  508.                 To call this function from your main routine you would use:
  509.                 <synopsis>
  510. int main(void)
  511. {
  512.     switch_rom_bank( 1 );  /* Select bank 1 with segment _CODE_1 */
  513.     silly_fun(5);      /* Prints "5 times 5 is 26" */
  514.  
  515.     return 0;
  516. }
  517.                 </synopsis>
  518.                 Note that you obviousally cannot do a <literal>switch_rom_bank</literal>
  519.                 call from inside any segment but _CODE as otherwise you'd switch
  520.                 yourself out.  Note also that all global routines like
  521.                 <literal>printf</literal> must fit within the limited 16k of bank 0.
  522.             </para>
  523.             <para>
  524.                 When linking all the object files together the number of banks used
  525.                 should be specified with the <literal>-Wl-yox</literal> and
  526.                 <literal>-Wl-yax</literal> flags and the MCB type with the
  527.                 <literal>-Wl-ytx</literal> flag.  The current supported values for
  528.                 x in <literal>-Wl-ytx</literal> are:
  529.             <synopsis>
  530.  
  531. 0 : ROM ONLY
  532. 1 : ROM+MBC1
  533. 2 : ROM+MBC1+RAM
  534. 3 : ROM+MBC1+RAM+BATTERY
  535. 5 : ROM+MBC2
  536. 6 : ROM+MBC2+BATTERY
  537.             </synopsis>
  538.             </para>
  539.         </sect1>
  540.         <sect1>
  541.             <title>Functions in RAM</title>
  542.             <para>
  543.                 It is possible to execute functions in RAM or HIRAM by first copying them
  544.                 there using <literal>memcpy()</literal> or <literal>himemcpy()</literal>
  545.                 and then calling them in similar ways to accessing <link linkend="gb-hw-memory">memory
  546.                 directly</link>.  See <literal>ram_fn.c</literal> for an example.
  547.             </para>
  548.         </sect1>
  549.     </chapter>
  550.     <chapter id="assembler">
  551.         <title>Assembly language</title>
  552.         <sect1>
  553.             <title>When C isn't fast enough</title>
  554.             <para>
  555.                 For many applications C is fast enough but in intensive functions you are
  556.                 sometimes better to write them in assembler.
  557.                 This section deals with interfacing your core C program with fast
  558.                 assembly sub routines.
  559.             </para>
  560.         </sect1>
  561.         <sect1>
  562.             <title>Calling convention</title>
  563.             <para>
  564.                 lcc in common with almost all C compilers prepends a '_' to any function names.
  565.                 For example the function <literal>printf(...)</literal> begins at the label
  566.                 <literal>_printf::</literal>.  Note that all functions are declared global.
  567.             </para>
  568.             <para>
  569.                 The parameters to a function are pushed in right to left order with no aligning -
  570.                 so a byte takes up a byte on the stack instead of the more natural word.  So
  571.                 for example the function <literal>int store_byte( UWORD addr, UBYTE byte)</literal>
  572.                 would push 'byte' onto the stack first then addr using a total of three bytes.
  573.                 As the return address is also pushed, the stack would contain:
  574.                 <itemizedlist>
  575.                     <listitem>
  576.                         <para>
  577.                             At SP+0 - the return address
  578.                         </para>
  579.                     </listitem>
  580.                     <listitem>
  581.                         <para>
  582.                             At SP+2 - addr
  583.                         </para>
  584.                     </listitem>
  585.                     <listitem>
  586.                         <para>
  587.                             At SP+4 - byte
  588.                         </para>
  589.                     </listitem>
  590.                 </itemizedlist>
  591.                 Note that the arguments that are pushed first are highest in the stack due to
  592.                 how the GB's stack grows downwards.
  593.             </para>
  594.             <para>
  595.                 The function returns in DE.  I'm not sure how a FP number is returned.
  596.             </para>
  597.         </sect1>
  598.         <sect1>
  599.             <title>Variables and registers</title>
  600.             <para>
  601.                 C normally expects registers to be preserved across a function call.  However
  602.                 in this case as DE is used as the return value and HL is used for anything,
  603.                 only BC needs to be preserved.
  604.             </para>
  605.             <para>
  606.                 Getting at C variables is slightly tricky due to how local variables are
  607.                 allocated on the stack.  However you shouldn't be using the local variables
  608.                 of a calling function in any case.  Global variables can be accessed by
  609.                 name by adding an underscore.
  610.             </para>
  611.         </sect1>
  612.         <sect1>
  613.             <title>Segments</title>
  614.             <para>
  615.                 The use of segments for code, data and variables is more noticeable in assembler.
  616.                 lcc defines a number of default segments - <literal>_CODE, _DATA</literal> and
  617.                 <literal>_BSS</literal> for storing code, static data and variables in
  618.                 respectively.  Two extra segments <literal>_HEADER</literal> and <literal>
  619.                 _HEAP</literal> exist for the GB header and malloc heap respectively.
  620.                 The order these segments are linked together is determined by <literal>crt0.s</literal>
  621.                 and is currently _CODE then _DATA in ROM and _BSS then _HEAP in RAM.  _HEAP
  622.                 is placed after _BSS so that all spare memory is available for the malloc routines.
  623.                 To place code in other than the first two banks, use the segments _CODE_x where x is
  624.                 the 16kB bank number.
  625.             </para>
  626.             <para>
  627.                 As the _BSS segment occurs outside the ROM area you can only use <literal>.ds</literal>
  628.                 to reserve space in it.
  629.             </para>
  630.             <para>
  631.                 While you don't have to use the _CODE and _DATA distinctions in assembler it is
  632.                 recommended for consistancys sake.
  633.             </para>
  634.         </sect1>
  635.     </chapter>
  636.     <chapter id="libraries">
  637.         <title>Libraries</title>
  638.         <sect1 id="text-lib">
  639.             <title>Text IO - console.h and output.s</title>
  640.             <para>
  641.                 Blah
  642.             </para>
  643.         </sect1>
  644.         <sect1 id="float-lib">
  645.             <title>Floating point support - fp_long.s</title>
  646.             <sect2>
  647.                 <title>Number format</title>
  648.                 <para>
  649.                     The number encoding used in GBDK was chosen make fp operations easier
  650.                     to implement.  Unfortunatly it doesnt conform to any standards but it
  651.                     does help speed the routines.  The high byte
  652.                     contains the sign and exponent, while the lower three bytes
  653.                     contain the mantissa.
  654.                 </para>
  655.                 <para>
  656.                     The most significant bit of the exponent is the sign bit which is
  657.                     set if the number is negative.  The lower seven bits are the exponent
  658.                     biased around 0x40.  The mantissa is normalised and includes the normally implicit
  659.                     one in the most significant bit.  Note that the mantissa for a negative
  660.                     number is not in twos complement.  A zero is represented by either
  661.                     by both the mantissa and exponent being zero.
  662.                 </para>
  663.                 <para>
  664.                     Some examples:
  665.                     <itemizedlist>
  666.                         <listitem>
  667.                             <para>
  668.                                 <literal>41 800000</literal> - sign = 0 (positive), exponent
  669.                                 equals 2^(0x41-0x40) = 2^1 = 2, mantissa = 0.800000 = 0.5
  670.                                 so the number is +1 * 2 * 0.5 or '1'
  671.                             </para>
  672.                         </listitem>
  673.                         <listitem>
  674.                             <para>
  675.                                 <literal>C4 A00000</literal> - sign = 1 (negative), exponent
  676.                                 equals 2^(0x44-0x40) = 2^(4) = 16, mantissa = 0.A00000 = 0.625
  677.                                 so the number is -1 * 16 * 0.625 or '-10'
  678.                             </para>
  679.                         </listitem>
  680.                     </itemizedlist>
  681.                 </para>
  682.             </sect2>
  683.             <sect2 id="float-lib-notes">
  684.                 <title>Notes</title>
  685.                     <para>
  686.                         The core floating point library functions fadd, fdiv, fsub and fmul were
  687.                         originally based on the algorithims in <ulink url="http://www.hitech.com.au">HI-TECH Software</ulink>
  688.                         's <ulink url="http://www.hitech.com.au/software/cpm/index.html">free CP/M C compiler</ulink>.
  689.                         However the code has been almost completly re-written and optimised and now
  690.                         only bears a passing resemblance to HI-TECH's code.
  691.                     </para>
  692.                     <para>
  693.                         The left hand argument to a function is stored in HLDE and the right hand on the top
  694.                         of the stack.  Most functions use static scratch registers in RAM which unfortunatly
  695.                         means that they arnt re-enterant.  As almost all of the functions in this section
  696.                         take floats as parameters and return floats, the format is different to the following
  697.                         sections.
  698.             </sect2>
  699.             <sect2 id="float-lib-funs">
  700.                 <title>Functions</title>
  701.                 <sect3 id="fadd32">
  702.                     <title>.fadd32</title>
  703.                     <sect4>
  704.                         <title>Description</title>
  705.                         <para>
  706.                             Perform a floating point addition on HLDE and the floating point number
  707.                             on the stack, returining the result in HLDE with the stack number
  708.                             removed.
  709.                         </para>
  710.                     </sect4>
  711.                     <sect4>
  712.                         <title>Method</title>
  713.                         <para>
  714.                             The two operands are recovered and the stack unjunked.  The sign is
  715.                             removed from both operands and the magnitudes compared.  If the
  716.                             difference in magnitude is greater than 24 bits then the greater
  717.                             number is returned.  If not, the smaller number is shifted right
  718.                             and its magnitude increased until both have the same magnitude.
  719.                             If an operand was originally negative, its magnitude is negated.
  720.                             The magnitudes are added and the new mantissa computed.
  721.                         </para>
  722.                     </sect4>
  723.                 </sect3>
  724.                 <sect3 id="fsub32">
  725.                     <title>.fsub32</title>
  726.                     <sect4>
  727.                         <title>Description</title>
  728.                         <para>
  729.                             Subtract the floating point number on the stack from the value in HLDE,
  730.                             returning the result in HLDE
  731.                         </para>
  732.                     </sect4>
  733.                     <sect4>
  734.                         <title>Method</title>
  735.                         <para>
  736.                             The sign bit on the stack operand is toggled which negates the right
  737.                             operand.  Execution then falls through to <link linkend="fadd32">.fadd32</link>
  738.                         </para>
  739.                     </sect4>
  740.                 </sect3>
  741.                 <sect3 id="fmul32">
  742.                     <title>.fmul32</title>
  743.                     <sect4>
  744.                         <title>Description</title>
  745.                         <para>
  746.                             Performs a floating point multiplication on the number in HLDE and the
  747.                             one on the stack.  Returns the result in HLDE with the stack operand removed.
  748.                         </para>
  749.                     </sect4>
  750.                     <sect4>
  751.                         <title>Method</title>
  752.                         <para>
  753.                             The product is stored in HLBC, the right hand operand in DE.ft1.ft0 and
  754.                             the left hand operand in .fw.  First the product is zeroed then a multiplication
  755.                             is done on the mantissas of the two operands.  The multiply is a standard
  756.                             (right shift - add if carry) but uses a few tricks to keep the result within
  757.                             32 bits instead of the maximum 48.  HLDE is then shifted down until H is zero.
  758.                             The number of shifts is added to the exponents of the two operands to give
  759.                             the resultant exponent.  Finally the sign bit is computed by a XOR of the signs
  760.                             of the operands.
  761.                         </para>
  762.                     </sect4>
  763.                 </sect3>
  764.                 <sect3 id="fdiv32">
  765.                     <title>.fdiv32</title>
  766.                     <sect4>
  767.                         <title>Description</title>
  768.                         <para>
  769.                             Divide the floating point number in HLDE by the value on the stack.  Return
  770.                             witht the result in HLDE and the stack unjunked.
  771.                         </para>
  772.                     </sect4>
  773.                     <sect4>
  774.                         <title>Method</title>
  775.                         <para>
  776.                             The divisor is stored in HLBC, the dividend in DE.fw1.fw0 and the quotent
  777.                             in .q.  The mantissa of the dividend is divided by the mantissa of the divisor.
  778.                             This uses the standard compare - subtract if less than - multiply by two
  779.                             method.  The quotient is then copied into HLDE and rotated right until
  780.                             H is zero.  The exponent is calculated by adding the number of shifts to
  781.                             the exponent of the left operand and subtracting the exponent of the right
  782.                             operand.  The sign bit is calculated using an XOR of the sign of the
  783.                             operands.
  784.                         </para>
  785.                     </sect4>
  786.                 </sect3>
  787.             </sect2>
  788.         </sect1>
  789.         <sect1>
  790.             <title>Full screen graphics - drawing.h</title>
  791.             <para>
  792.                 Blah
  793.             </para>
  794.         </sect1>
  795.         <sect1 id="graphics">
  796.             <title>Graphics/Tile functions</title>
  797.             <para>
  798.                 GBDK graphic primitives allow the host to manage tiles, background,
  799.                 window, and sprites. Some of these primitives depend on the contents
  800.                 of the LCDC register, which specify the addresses in the VRAM at which
  801.                 graphics data are located. Therefore, the LCDC register must be set
  802.                 prior to using these primitives.
  803.             </para>
  804.             <para>
  805.                 By default, the background and window TDT is located at addresses
  806.                 0x8800-0x97FF, the sprite TDT at addresses 0x8000-0x8FFF, the BTM at
  807.                 addresses 0x9800-0x9BFF, and the WTM at addresses 0x9C00-0x9FFF.  It
  808.                 is possible to modify these addresses (except the sprite TDT) using
  809.                 the LCDC register.
  810.             </para>
  811.             <sect2 id="graphics-fun">
  812.                 <title>Functions</title>
  813.                 <sect3 id="setxxx-getxxx">
  814.                     <title>set_xxx_data / get_xxx_data</title>
  815.                     <para>
  816.                         <synopsis>
  817. void
  818. set_bkg_data(UBYTE first_tile,
  819.              UBYTE nb_tiles,
  820.              unsigned char *data);
  821.  
  822. void
  823. set_win_data(UBYTE first_tile,
  824.              UBYTE nb_tiles,
  825.              unsigned char *data);
  826.  
  827. void
  828. set_sprite_data(UBYTE first_tile,
  829.                 UBYTE nb_tiles,
  830.                 unsigned char *data);
  831.  
  832. void
  833. set_data(unsigned char *vram_addr,
  834.          unsigned char *data,
  835.          UWORD len);
  836.  
  837. void
  838. get_bkg_data(UBYTE first_tile,
  839.              UBYTE nb_tiles,
  840.              unsigned char *data);
  841.  
  842. void
  843. get_win_data(UBYTE first_tile,
  844.              UBYTE nb_tiles,
  845.              unsigned char *data);
  846.  
  847. void
  848. get_sprite_data(UBYTE first_tile,
  849.                 UBYTE nb_tiles,
  850.                 unsigned char *data);
  851.  
  852. void
  853. get_data(unsigned char *data,
  854.          unsigned char *vram_addr,
  855.          UWORD len);
  856.                          </synopsis>
  857.                     </para>
  858.                     <sect4>
  859.                         <title>Description</title>
  860.                         <para>
  861.                             The <literal>set_bkg_data()</literal>, <literal>set_win_data()</literal>, and
  862.                             <literal>set_sprite_data()</literal> functions copy tile data to the
  863.                             background, window, or sprite TDT in VRAM. The <literal>get_bkg_data()</literal>,
  864.                             <literal>get_win_data()</literal>, and <literal>get_sprite_data()</literal> functions
  865.                             copy data from VRAM to an address specified by the user. The address
  866.                             of data in VRAM depends of the contents of the LCDC register.
  867.                         </para>
  868.                         <para>
  869.                             The <literal>set_data()</literal> function copies data to any address in VRAM.
  870.                             The <literal>get_data()</literal> function copies data from any address in
  871.                             VRAM.
  872.                         </para>
  873.                         <para>
  874.                             The operations that read data can be used to save the current state of
  875.                             the screen (for instance for displaying a dialog box, and restoring
  876.                             the screen afterwards).
  877.                         </para>
  878.                     </sect4>
  879.                     <sect4>
  880.                         <title>Paramenters</title>
  881.                         <para>
  882.                             <literal>first_tile</literal>: number of the first tile in VRAM (between
  883.                               0 and 255).
  884.                         </para>
  885.                         <para>
  886.                             <literal>nb_tiles</literal>: number of tiles to copy (0 for copying 256
  887.                               tiles).
  888.                         </para>
  889.                         <para>
  890.                             <literal>data</literal>: pointer to the user tile data.
  891.                         </para>
  892.                         <para>
  893.                             <literal>vram_addr</literal>: address in VRAM.
  894.                         </para>
  895.                         <para>
  896.                             <literal>len</literal>: number of bytes to copy.
  897.                         </para>
  898.                     </sect4>
  899.                     <sect4>
  900.                         <title>Returns</title>
  901.                         <para>
  902.                             Nothing.
  903.                         </para>
  904.                     </sect4>
  905.                 </sect3>
  906.                 <sect3 id="setxxx-tiles">
  907.                     <title>set_xxx_tiles / get_xxx_tiles</title>
  908.                     <para>
  909.                         <synopsis>
  910. void
  911. set_bkg_tiles(UBYTE x,
  912.               UBYTE y,
  913.               UBYTE w,
  914.               UBYTE h,
  915.               unsigned char *tiles);
  916.  
  917. void
  918. set_win_tiles(UBYTE x,
  919.               UBYTE y,
  920.               UBYTE w,
  921.               UBYTE h,
  922.               unsigned char *tiles);
  923.  
  924. void
  925. set_tiles(UBYTE x,
  926.           UBYTE y,
  927.           UBYTE w,
  928.           UBYTE h,
  929.           unsigned char *vram_addr,
  930.           unsigned char *tiles);
  931.  
  932. set_sprite_tile(UBYTE nb,
  933.                 UBYTE tile);
  934.  
  935. void
  936. get_bkg_tiles(UBYTE x,
  937.               UBYTE y,
  938.               UBYTE w,
  939.               UBYTE h,
  940.               unsigned char *tiles);
  941.  
  942. void
  943. get_win_tiles(UBYTE x,
  944.               UBYTE y,
  945.               UBYTE w,
  946.               UBYTE h,
  947.               unsigned char *tiles);
  948.  
  949. void
  950. get_tiles(UBYTE x,
  951.           UBYTE y,
  952.           UBYTE w,
  953.           UBYTE h,
  954.           unsigned char *tiles,
  955.           unsigned char *vram_addr);
  956.  
  957. UBYTE get_sprite_tile(UBYTE nb);
  958.                         </synopsis>
  959.                     </para>
  960.                     <sect4>
  961.                         <title>Description</title>
  962.                         <para>
  963.                             The <literal>set_bkg_tiles()</literal> and <literal>set_win_tiles()</literal>
  964.                             functions copy a rectangular area of background or window tile numbers
  965.                             to the BTM in VRAM. The <literal>get_bkg_tiles()</literal> and
  966.                             <literal>get_win_tiles()</literal> functions copy data from VRAM to an address
  967.                             specified by the user.  The address of tile numbers in VRAM depends of
  968.                             the contents of the LCDC register.
  969.                         </para>
  970.                         <para>
  971.                             The <literal>set_tiles()</literal> function copies a rectangular area of tile
  972.                             numbers to any address in VRAM (this address will be generally 0x8000
  973.                             or 0x8800). The <literal>get_tiles()</literal> function copies data from VRAM
  974.                             to an address specified by the user.
  975.                         </para>
  976.                         <para>
  977.                             The <literal>set_sprite_tiles()</literal> function set the tile number of a
  978.                             specific sprite. The <literal>get_sprite_tiles()</literal> function returns
  979.                             the tile number of a sprite. These functions do not directly access
  980.                             the VRAM.
  981.                         </para>
  982.                         <para>
  983.                             The operations that read data can be used to save the current state of
  984.                             the screen (for instance for displaying a dialog box, and restoring
  985.                             the screen afterwards).
  986.                         </para>
  987.                     </sect4>
  988.                     <sect4>
  989.                         <title>Parameters</title>
  990.                         <para>
  991.                             <literal>x</literal>: horizontal coordinate of the top-left corner of the
  992.                               rectangular area in VRAM.
  993.                         </para>
  994.                         <para>
  995.                             <literal>y</literal>: vertical coordinate of the top-left corner of the
  996.                               rectangular area in VRAM.
  997.                         </para>
  998.                         <para>
  999.                             <literal>w</literal>: width of the the rectangular area in VRAM.
  1000.                         </para>
  1001.                         <para>
  1002.                             <literal>h</literal>: height of the the rectangular area in VRAM.
  1003.                         </para>
  1004.                         <para>
  1005.                             <literal>tiles</literal>: pointer to the user tile numbers. The size of
  1006.                               the tile numbers should be <literal>w*h</literal>.
  1007.                         </para>
  1008.                         <para>
  1009.                             <literal>vram_addr</literal>: address in VRAM.
  1010.                         </para>
  1011.                         <para>
  1012.                             <literal>nb</literal>: index of the sprite to access (between 0 and 39).
  1013.                         </para>
  1014.                         <para>
  1015.                             <literal>tile</literal>: tile number of the sprite.
  1016.                         </para>
  1017.                     </sect4>
  1018.                     <sect4>
  1019.                         <title>Returns</title>
  1020.                         <para>
  1021.                             The <literal>get_sprite_tiles()</literal> function returns the tile number of
  1022.                             the sprite.
  1023.                         </para>
  1024.                     </sect4>
  1025.                 </sect3>
  1026.                 <sect3>
  1027.                     <title>move_xxx</title>
  1028.                     <para>
  1029.                         <synopsis>
  1030. void
  1031. move_bkg(UBYTE x,
  1032.          UBYTE y);
  1033.  
  1034. void
  1035. move_win(UBYTE x,
  1036.          UBYTE y);
  1037.  
  1038. void
  1039. move_sprite(UBYTE nb,
  1040.             UBYTE x,
  1041.             UBYTE y);
  1042.                         </synopsis>
  1043.                     </para>
  1044.                     <sect4>
  1045.                         <title>Description</title>
  1046.                         <para>
  1047.                             The <literal>move_bkg()</literal> and <literal>move_win()</literal> functions modify the
  1048.                             position of the background or window display.  These functions expect
  1049.                             the absolute value of the new position. Note that these functions
  1050.                             should preferably not be used during screen redraw. To avoid unwanted
  1051.                             visual distortions, it is better to call these functions upon VBL.
  1052.                         </para>
  1053.                         <para>
  1054.                             The <literal>move_sprite()</literal> function modifies the position of a
  1055.                             specific sprite.  This function expects the absolute value of the new
  1056.                             position. It does not directly access the VRAM.
  1057.                         </para>
  1058.                     </sect4>
  1059.                     <sect4>
  1060.                         <title>Parameters</title>
  1061.                         <para>
  1062.                             <literal>x</literal>: horizontal coordinate of the new display position.
  1063.                             <literal>y</literal>: vertical coordinate of the new display position.
  1064.                             <literal>nb</literal>: index of the sprite to access (between 0 and 39).
  1065.                         </para>
  1066.                     </sect4>
  1067.                     <sect4>
  1068.                         <title>Returns</title>
  1069.                         <para>
  1070.                             Nothing.
  1071.                         </para>
  1072.                     </sect4>
  1073.                 </sect3>
  1074.                 <sect3 id="scroll-xxx">
  1075.                     <title>scroll_xxx</title>
  1076.                     <para>
  1077.                         <synopsis>
  1078. void
  1079. scroll_bkg(BYTE x,
  1080.            BYTE y);
  1081.  
  1082. void
  1083. scroll_win(BYTE x,
  1084.            BYTE y);
  1085.  
  1086. void
  1087. scroll_sprite(UBYTE nb,
  1088.               BYTE x,
  1089.               BYTE y);
  1090.                         </synopsis>
  1091.                     </para>
  1092.                     <sect4>
  1093.                         <title>Description</title>
  1094.                         <para>
  1095.                             The <literal>scroll_bkg()</literal> and <literal>scroll_win()</literal> functions modify
  1096.                             the position of the background or window display.  These functions
  1097.                             expect a relative displacement relative to the current position. Note
  1098.                             that these functions should preferably not be used during screen
  1099.                             redraw. To avoid unwanted visual distortions, it is better to call
  1100.                             these functions upon VBL.
  1101.  
  1102.                             The <literal>scroll_sprite()</literal> function modifies the position of a
  1103.                             specific sprite.  This function expects a relative displacement
  1104.                             relative to the current position. It does not directly access the
  1105.                             VRAM.
  1106.                         </para>
  1107.                     </sect4>
  1108.                     <sect4>
  1109.                         <title>Parameters</title>
  1110.                         <para>
  1111.                             <literal>x</literal>: horizontal displacement relative to the current
  1112.                               display position.
  1113.                         </para>
  1114.                         <para>
  1115.                             <literal>y</literal>: vertical displacement relative to the current
  1116.                               display position.
  1117.                         </para>
  1118.                         <para>
  1119.                             <literal>nb</literal>: index of the sprite to access (between 0 and 39).
  1120.                         </para>
  1121.                     </sect4>
  1122.                     <sect4>
  1123.                         <title>Returns</title>
  1124.                         <para>
  1125.                             Nothing.
  1126.                         </para>
  1127.                     </sect4>
  1128.                 </sect3>
  1129.                 <sect3>
  1130.                     <title>set_sprite_prop / get_sprite_prop</title>
  1131.                     <para>
  1132.                         <synopsis>
  1133. /* Sprite properties bits */
  1134.  
  1135. #define S_PALETTE    0x10U
  1136. #define S_FLIPX      0x20U
  1137. #define S_FLIPY      0x40U
  1138. #define S_PRIORITY   0x80U
  1139.  
  1140. void
  1141. set_sprite_prop(UBYTE nb,
  1142.                 UBYTE prop);
  1143.  
  1144. UBYTE
  1145. get_sprite_prop(UBYTE nb);
  1146.                         </synopsis>
  1147.                     </para>
  1148.                     <sect4>
  1149.                         <title>Description</title>
  1150.                         <para>
  1151.                             The <literal>set_sprite_prop()</literal> function modifies the attributed of a
  1152.                             specific sprite. The <literal>get_sprite_prop()</literal> function returns the
  1153.                             attributed of a sprite. These functions do not directly access the
  1154.                             VRAM.
  1155.                         </para>
  1156.                     </sect4>
  1157.                     <sect4>
  1158.                         <title>Paramters</title>
  1159.                         <para>
  1160.                             <literal>nb</literal>: index of the sprite to access (between 0 and 39).
  1161.                         </para>
  1162.                         <para>
  1163.                             <literal>prop</literal>: new value of the sprite attributes.
  1164.                         </para>
  1165.                     </sect4>
  1166.                     <sect4>
  1167.                         <title>Returns</title>
  1168.                         <para>
  1169.                             The <literal>get_sprite_prop()</literal> returns the attributes of the sprite.
  1170.                         </para>
  1171.                     </sect4>
  1172.                 </sect3>
  1173.             </sect2>
  1174.         </sect1>
  1175.         <sect1>
  1176.             <title>Joypad - gb.h</title>
  1177.             <sect2>
  1178.                 <title>Functions</title>
  1179.                 <sect3>
  1180.                     <title>joypad / waitpad / waitpadup</title>
  1181.                     <para>
  1182.                         <synopsis>
  1183. /* Joypad bits */
  1184.  
  1185. #define    J_START      0x80U
  1186. #define    J_SELECT     0x40U
  1187. #define    J_B          0x20U
  1188. #define    J_A          0x10U
  1189. #define    J_DOWN       0x08U
  1190. #define    J_UP         0x04U
  1191. #define    J_LEFT       0x02U
  1192. #define    J_RIGHT      0x01U
  1193.  
  1194. UBYTE
  1195. joypad(void);
  1196.  
  1197. UBYTE
  1198. waitpad(UBYTE mask);
  1199.  
  1200. void
  1201. waitpadup(void);
  1202.                         </synopsis>
  1203.                     </para>
  1204.                     <sect4>
  1205.                         <title>Description</title>
  1206.                         <para>
  1207.                             The <literal>joypad()</literal> function reads the current status of the
  1208.                             joypad. It does not block the current thread of control. The joypad
  1209.                             status returned by the function uses one bit for each button,
  1210.                             according to the definitions given above.
  1211.                         </para>
  1212.                         <para>
  1213.                             The <literal>waitpad()</literal> function waits for any button from a given mask
  1214.                             to be pushed. The <literal>waitpadup()</literal> function waits for all buttons
  1215.                             to be released.
  1216.                         </para>
  1217.                     </sect4>
  1218.                     <sect4>
  1219.                         <title>Parameters</title>
  1220.                         <para>
  1221.                             <literal>mask</literal>: set of buttons to wait for.
  1222.                         </para>
  1223.                     </sect4>
  1224.                     <sect4>
  1225.                         <title>Returns</title>
  1226.                         <para>
  1227.                             The <literal>joypad()</literal> and \<literal>waitpadup()</literal> functions return the
  1228.                             joypad status.
  1229.                         </para>
  1230.                     </sect4>
  1231.                 </sect3>
  1232.             </sect2>
  1233.         </sect1>
  1234.         <sect1 id="hardware-h">
  1235.             <title>Hardware registers - hardware.h</title>
  1236.             <para>
  1237.                 Blah
  1238.             </para>
  1239.         </sect1>
  1240.         <sect1>
  1241.             <title>Types - types.h</title>
  1242.             <para>
  1243.                 Blah
  1244.             </para>
  1245.         </sect1>
  1246. <sect1 id="malloc-lib">
  1247.     <title>malloc, free and related functions - stdlib.h</title>
  1248.     <sect2>
  1249.         <title>Functions</title>
  1250.         <sect3 id="malloc"><title>malloc</title>
  1251.             <para>
  1252.                 <synopsis>void *malloc( <link linkend="size-t">size_t</link> numbytes )</synopsis>
  1253.                 Allocate numbytes of memory from the free memory pool and return 
  1254.                 a pointer to the base of the newly allocated region.
  1255.             </para>
  1256.             <sect4>
  1257.                 <title>Description</title>
  1258.                 <para>
  1259.                     Note that the memory is not cleared upon allocation.
  1260.                 </para>
  1261.             </sect4>
  1262.             <sect4>
  1263.                 <title>Parameters</title>
  1264.                 <para>
  1265.                     numbytes:  The number of bytes to allocate
  1266.                 </para>
  1267.             </sect4>
  1268.             <sect4>
  1269.                 <title>Returns</title>
  1270.                 <para>
  1271.                     On success, returns a pointer to the newly allocated region.
  1272.                     On failure returns <link linkend="null">NULL</link>.
  1273.                 </para>
  1274.             </sect4>
  1275.         </sect3>
  1276.         <sect3 id="calloc"><title>calloc</title>
  1277. <para>
  1278. <synopsis>void *calloc( <link linkend="size-t">size_t</link> nmem, <link linkend="size-t">size_t</link> size )</synopsis>
  1279. Attempt to allocate space for nmem objects of size size and return a pointer to the allocated region.
  1280. </para>
  1281. <sect4><title>Description</title>
  1282. <para>
  1283. calloc is very similar to malloc but it also clears (fills with zero) the memory region
  1284. before returning.
  1285. </para></sect4>
  1286. <sect4><title>Parameters</title>
  1287. <para>
  1288. size: size of one object
  1289. </para>
  1290. <para>
  1291. nmem:  Number of objects to allocate space for
  1292. </para></sect4>
  1293. <sect4><title>Returns</title>
  1294. <para>
  1295. On success, returns a pointer to the newly allocated and cleared region.
  1296. On failure, returns <link linkend="null">NULL</link>.
  1297. </para></sect4>
  1298. </sect3>
  1299.  
  1300. <sect3 id="realloc"><title>realloc</title>
  1301. <para>
  1302. <synopsis>
  1303. void *realloc( void *current, <link linkend="size-t">size_t</link> size )</synopsis>
  1304. Attempt to re-size a currently allocated region.
  1305. </para>
  1306. <sect4><title>Description</title>
  1307. <para>
  1308. realloc is used to resize a currently allocated block without loosing the 
  1309. data contained within.  If the current block is larger than the requested 
  1310. block the the trailing data is lost.  Note that the end of the block is
  1311. not cleared if the current block is smaller than the requested one.
  1312. If current is NULL, then this is equivalent to <link linkend="malloc">malloc</link>.
  1313. If size is zero, then this is equivalent to <link linkend="free">free</link>.
  1314. </para></sect4>
  1315. <sect4><title>Parameters</title>
  1316. <para>
  1317. current: Pointer to the currently allocated block.
  1318. </para>
  1319. <para>
  1320. size: Size of the new block
  1321. </para></sect4>
  1322. <sect4><title>Returns</title>
  1323. <para>
  1324. On success returns a pointer to the newly allocated block.  Note that the new
  1325. block may be at a different location to the old.
  1326. On failure or if size is zero, then NULL is returned.
  1327. </para></sect4>
  1328. </sect3>
  1329. <sect3 id="free"><title>free</title>
  1330. <para>
  1331. <synopsis>int free( void *region )</synopsis>
  1332. Free a previously allocated region.
  1333. </para>
  1334. <sect4><title>Description</title>
  1335. <para>
  1336. Attempts to free a region previously allocated by <link linkend="malloc">malloc</link>, 
  1337. <link linkend="realloc">realloc</link> or <link linkend="calloc">calloc</link>.  Note that only valid regions can
  1338. be freed.  Note also that this prototype differs from the standard C free
  1339. as it returns an error code.
  1340. </para></sect4>
  1341. <sect4><title>Parameters</title>
  1342. <para>
  1343. region:  Pointer to a previously allocated region.
  1344. </para></sect4>
  1345. <sect4><title>Returns</title>
  1346. <para>
  1347. On success, returns zero (0).
  1348. If the region is already free, returns -1.
  1349. If the region was never allocated, returns -2.
  1350. </para></sect4>
  1351. </sect3></sect2>
  1352. <sect2><title>Data types</title>
  1353. <sect3 id="null"><title>NULL</title>
  1354. <para>
  1355. NULL is returned by <link linkend="malloc">malloc</link> and others upon failure.  Currently
  1356. defined to be equal to zero.
  1357. </para>
  1358. </sect3>
  1359. <sect3 id="size-t"><title>size_t:  UWORD</title>
  1360. <para>
  1361. size_t is used to specify the size of an object in bytes.  As the GB has an
  1362. 8 bit processor with a 16 bit address space, size_t is currently defined as
  1363. a UWORD.  Note that due to the banked nature of most GB programs, it might
  1364. be changed to UDWORD at a later date.
  1365. </para></sect3>
  1366. </sect2>
  1367. <sect2><title>Implementation</title>
  1368. <para>
  1369. This malloc library is implemented using a simple signally linked list of hunks
  1370. where a hunk is a a header and section of memory that can be either free or used.
  1371. There is nothing particularly clever about the allocation algorithms.  I'm
  1372. an engineer as opposed to a computer scientist, so if the code gets the job
  1373. done then it's close enough.  Note that I do not know how well this system will
  1374. hold up against heavy fragmentation caused by allocating many small blocks
  1375. and keeping some of them.  However, I also cant think of a program that you'd
  1376. want to run on a GB that would do this.
  1377. </para>
  1378. <sect3><title>Functions</title>
  1379. <sect4 id="malloc-init"><title>malloc_init</title>
  1380. <para>
  1381. <synopsis>int malloc_init( void )</synopsis>
  1382. If the malloc system is currently uninitialised, initialise it.
  1383. </para>
  1384. <sect5><title>Description</title>
  1385. <para>
  1386. Checks to see if the header malloc_first is valid by checking its
  1387. magic number.  If it is not, initialise it by marking it as free, setting it
  1388. to occupy all of the free ram in the area C000h to D000h, setting the
  1389. <link linkend="mmalloc-hunk">region header</link> pointer to NULL and finally setting the
  1390. <link linkend="malloc-magic">magic number</link>.
  1391. </para></sect5>
  1392. <sect5><title>Parameters</title>
  1393. <para>
  1394. None
  1395. </para></sect5>
  1396. <sect5><title>Returns</title>
  1397. <para>
  1398. On success, returns zero (0).
  1399. If the malloc system is already setup, return -1.
  1400. </para></sect5>
  1401. </sect4>
  1402. <sect4 id="malloc-gc"><title>malloc_gc</title>
  1403. <para>
  1404. <synopsis>void malloc_gc( void )</synopsis>
  1405. Perform garbage collection on the malloc hunk list by joining consecutive free
  1406. blocks.
  1407. </para>
  1408. <sect5><title>Description</title>
  1409. <para>
  1410. malloc_gc is called by <link linkend="malloc">malloc</link> when an attempt to allocate a
  1411. region fails.  malloc_gc attempts to improve the situation by scanning through
  1412. the malloc hunk list and joining adjacent free blocks into one larger block.
  1413. In each scan, if two adjacent free blocks are found then they are combined and
  1414. the scan continued from the first block.  At the end of a scan, if any
  1415. combinations were made then the list is rescanned.  I'm not really sure why the
  1416. rescan is there as in theory all combinations should be made on the first pass.
  1417. </para></sect5>
  1418. <sect5><title>Parameters</title>
  1419. <para>
  1420. None
  1421. </para></sect5>
  1422. <sect5><title>Returns</title>
  1423. <para>
  1424. Nothing
  1425. </para></sect5>
  1426. </sect4>
  1427. </sect3>
  1428. <sect3><title>Data types</title>
  1429. <sect4 id="mmalloc-hunk"><title>mmalloc_hunk</title>
  1430. <para>
  1431. <synopsis>
  1432. struct smalloc_hunk {
  1433.     UBYTE magic;
  1434.     pmmalloc_hunk    next;
  1435.     UWORD size;
  1436.     int status;
  1437. };
  1438. </synopsis>
  1439. mmalloc_hunk is an internal structure used by the <link linkend="malloc">malloc</link> library
  1440. to keep track of allocated and free regions of memory.
  1441. </para>
  1442. <sect5><title>Members</title>
  1443. <para>
  1444. magic:  A magic number that identifies this as a valid mmalloc_hunk
  1445. next:  Pointer to the next hunk, <link linkend="null">NULL</link> if this is the last.
  1446. size:  Size in bytes of the hunk.
  1447. status:  Current status of the block that this hunk refers to.  One of
  1448. MALLOC_UNUSED (0), MALLOC_FREE (1) and MALLOC_USED (2).  I have no idea why
  1449. I defined both a MALLOC_UNUSED and a MALLOC_FREE :)
  1450. </para></sect5>
  1451. </sect4>
  1452. <sect4 id="malloc-magic"><title>MALLOC_MAGIC:  UBYTE</title>
  1453. <para>
  1454. The magic number associated with a valid malloc hunk header.  Currently set
  1455. at a really boring 123.  Suggestions for something better will be greatly
  1456. appreciated.
  1457. </para>
  1458. </sect4>
  1459. </sect3>
  1460. <sect3><title>Notes</title>
  1461. <para>
  1462. The <link linkend="mmalloc-hunk">header</link> for a hunk occurs just before the
  1463. region.  Any errant programs that write past their region could overwrite
  1464. this header and break the linked list.  But you get that.  Most routines
  1465. check the magic number while walking the list and abort if a broken
  1466. header is found.
  1467. </para>
  1468. <para>
  1469. The amount of memory free after static variables are allocated is determined
  1470. by using a new linker area called _HEAP, defined in crt0.s.  _HEAP occurs
  1471. after _BSS, so it should occur at the start of free memory.  The only data
  1472. initially in _HEAP is a reference to malloc_heap_start which is used
  1473. by <link linkend="malloc-init">malloc_init</link>.  Note that it is possibly on a real GB for the
  1474. magic number to occur in a bad place.  This should be fixed in crt0.s at
  1475. the initialisation time.  malloc also shares the ram with the stack.
  1476. Currently the problem of the stack growing down into allocated memory is
  1477. lessened by allocating from low memory first and by providing a 512 byte
  1478. buffer (set in <link linkend="malloc-init">malloc_init</link>).
  1479. </para>
  1480. <para>
  1481. On cartridges with internal memory an extra 8k from A000h to BFFFh is
  1482. available.  Unfortunately <link linkend="free">free</link> assumes that hunks are consecutive
  1483. which causes problems.  Two solutions are shifting _BSS to start at A000h
  1484. or defining an extra flag in <link linkend="mmalloc-hunk">the header</link> that is set if
  1485. the next hunk is consecutive to the current one.  The second option would 
  1486. also allow paged ram to be used, although it would have to be managed carefully.
  1487. </para>
  1488. </sect3>
  1489. </sect2>
  1490. </sect1>
  1491. <sect1 id="font-lib">
  1492. <title>Support for multiple fonts - font.h</title>
  1493. <sect2><title>Functions</title>
  1494. <sect3 id="font-init"><title>font_init</title>
  1495. <para>
  1496. <synopsis>
  1497. void init_font(void)
  1498. </synopsis>
  1499. Initialise the font system by clearing all font handles and releasing all tiles.
  1500. </para>
  1501. <sect4><title>Description</title>
  1502. <para>
  1503. Initialises the font system.  This routine should be called at the start of the program before any calls to <link linkend="font-load">font_load</link>.
  1504. </para></sect4>
  1505. <sect4><title>Parameters</title>
  1506. <para>
  1507. None.
  1508. </para></sect4>
  1509. <sect4><title>Returns</title>
  1510. <para>
  1511. Nothing.
  1512. </para></sect4>
  1513. </sect3>
  1514. <sect3 id="font-load"><title>font_load</title>
  1515. <para>
  1516. <synopsis>
  1517. <link linkend="font-handle">FONT_HANDLE</link> load_font( void *<link linkend="font-structure">font_structure</link> )
  1518. </synopsis>
  1519. Attempt to load the font font, returning a <link linkend="font-handle">FONT_HANDLE</link> on success or NULL on failure.
  1520. </para>
  1521. <sect4><title>Description</title>
  1522. <para>
  1523. font_load should be called once for each font that is required.  Note that currently there is no way to unload a font except by calling font_init().
  1524. </para></sect4>
  1525. <sect4><title>Parameters</title>
  1526. <para>
  1527. font: pointer to the base of a valid font structure
  1528. </para></sect4>
  1529. <sect4><title>Returns</title>
  1530. <para>
  1531. On success, returns a <link linkend="font-handle">FONT_HANDLE</link>.  On failure, returns NULL (0)
  1532. </para></sect4>
  1533. </sect3>
  1534. <sect3 id="font-set"><title>font_set</title>
  1535. <para>
  1536. <synopsis>
  1537. void font_set( <link linkend="font-handle">FONT_HANDLE</link> font_handle )
  1538. </synopsis>
  1539. Set the current font to the previously loaded font font_handle
  1540. </para>
  1541. <sect4><title>Description</title>
  1542. <para>
  1543. set_font changes current output font to the one specified by font_handle
  1544. </para></sect4>
  1545. <sect4><title>Parameters</title>
  1546. <para>
  1547. font_handle: handle from a previous <link linkend="font-load">font_load</link> call.
  1548. </para></sect4>
  1549. <sect4><title>Returns</title>
  1550. <para>
  1551. Nothing.
  1552. </para></sect4>
  1553. <sect4><title>Bugs</title>
  1554. <para>
  1555. No check is made to see if font_handle is a valid font handle.
  1556. </para></sect4>
  1557. </sect3>
  1558. </sect2>
  1559. <sect2><title>Data types</title>
  1560. <sect3 id="font-handle"><title>FONT_HANDLE:  UWORD</title>
  1561. <sect4><title>Description</title>
  1562. <para>
  1563. A FONT_HANDLE is a 16 bit value returned from <link linkend="font-load">font_load</link> and used by <link linkend="font-set">font_set</link>.  Physically it is a pointer to an entry in the font_table.
  1564. </para>
  1565. </sect4>
  1566. </sect3>
  1567. <sect3 id="font-structure"><title>font_structure</title>
  1568. <sect4><title>Description</title>
  1569. <para>
  1570. A font_structure is a container for the data related to a font, including the <link linkend="font-structure-encoding">encoding data</link> and <link linkend="font-structure-tile-data">tile</link> (bitmap) image data.
  1571. Due to the variable length nature of the encoding table and the tile data no default C structure exists.
  1572. </para></sect4>
  1573. <sect4><title>Format</title>
  1574. <para>
  1575. A font structure is made up of four fields - the font type, the number of tiles used, the encoding table and the tile data.
  1576. </para>
  1577. <sect5 id="font-structure-type"><title>type:  UBYTE</title>
  1578. <para>
  1579. The Font type is a single bit that describes the encoding table and the format of
  1580. the tile data.  The encoding table length is specified by the lower two bits: 
  1581. 00:  256 byte encoding table.
  1582. 01:  128 byte encoding table.
  1583. 10:  No encoding table - the font is 256 tiles long.
  1584. 11 is reserved.
  1585. The third bit (0x04) is used to determine if the tile data is compressed.  Many tiles do not use shades of grey, and so can be represented in 8 bytes instead of 16.  If bit 2 is set, then the tiles are assumed to be 8 bytes long and are expanded to 16 bytes at the load stage.
  1586. </para></sect5>
  1587. <sect5 id="font-structure-num-tiles"><title>num_tiles:  UBYTE</title>
  1588. <para>
  1589. num_tiles gives the number of tiles present in the tile data and hence the number of tiles required by the font.
  1590. </para></sect5>
  1591. <sect5 id="font-structure-encoding"><title>encoding:  array of UBYTE</title>
  1592. <para>
  1593. The encoding table is an array that maps an ASCII character to the appropriate tile in the tile data.  For example, suppose that the letter 'A' was the tenth tile.  Then the 65th (the ASCII code for 'A') entry in the encoding table would be 10.
  1594. Any ASCII characters that don't have a corresponding tile should be mapped to a default tile.  Space is recommended tile.
  1595. </para></sect5>
  1596. <sect5 id="font-structure-tile-data"><title>tile_data:  array of UBYTE</title>
  1597. <para>
  1598. The final field is the actual tile data.  Note that tile numbering starts from zero.
  1599. </para></sect5>
  1600. </sect4>
  1601. </sect3>
  1602. </sect2>
  1603. <sect2><title>Backwards compatibilty</title>
  1604. <para>The original text routines were replaced by the font routines in GBDK 2.0.18.  This
  1605. section describes the differences and compatibility between the old and new text routines.</para>
  1606. <para>The old font routines stored a bitmap of the entire IBM-ASCII character set in the
  1607. Gaemboy tiles, such that the ASCII value of the letter mapped to the appropriate tile - for example,
  1608. the bitmap of an 'A' (ASCII 65) was stored in tile 65.  The new system allows multiple fonts to fit
  1609. into the same 256 tiles by removing unused characters - for example, if one font only needs the
  1610. letters 'A-Z' and numbers '0-9' (36 tiles), then the remaining 220 tiles can be used for
  1611. other fonts or game tiles.</para>
  1612. <para>If no fonts are loaded before the first call to putchar() then the original IBM-ASCII font is
  1613. automatically loaded.  This should make the font routines backwards compatible with older code and
  1614. standard C.  Note that the text input routines currently only work with the IBM-ASCII font.</para>
  1615. <para>One side effect is that the IBM-ASCII font is always linked in occuping 2.3k of ROM, even
  1616. if it is not used.  If the extra ROM is required, add the line:</para>
  1617. <synopsis>
  1618. UBYTE font_ibm_fixed[];
  1619. or
  1620. _font_ibm_fixed::
  1621. </synopsis>
  1622. <para>into the project.  Note that in 2.0.18, the graphics mode text routines only use the
  1623. IBM-ASCII font.</para>
  1624. <para>Fonts can also be used to store game tiles.  To make the tiles allocated more predictable,
  1625. load the game tile font first, as the first tile in the font will be allocated to tile 01h (tile 00h
  1626. is always clear).  Game tile fonts should use 'no encoding' for their encoding table type to save
  1627. memory.  Two features allow the standard C routines to also be used for game tiles - namely M_NO_INTERP and M_NO_SCROLL.  The first stops the routines from interpreting carridge returns (\n), the
  1628. second stops the screen from scrolling.  Use 
  1629. <synopsis>
  1630. mode(get_mode() | M_NO_INTERP | M_NO_SCROLL);
  1631. </synopsis>
  1632. to turn both on.  See font_draw in Michael Hopes 'metro' package for an example.
  1633. </para>
  1634. </sect2>
  1635. </sect1>
  1636. </chapter>
  1637. </book>
  1638.